home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kwallet.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  16.3 KB  |  521 lines
  1. /* This file is part of the KDE project
  2.  *
  3.  * Copyright (C) 2002-2004 George Staikos <staikos@kde.org>
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public License
  16.  * along with this library; see the file COPYING.LIB.  If not, write to
  17.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19.  */ 
  20.  
  21.  
  22. #ifndef _KWALLET_H
  23. #define _KWALLET_H
  24.  
  25. #include <qglobal.h>
  26. #ifdef Q_OS_UNIX
  27.  
  28. #include <qstring.h>
  29. #include <qstringlist.h>
  30. #include <qobject.h>
  31. #include <dcopobject.h>
  32.  
  33. class DCOPRef;
  34.  
  35. /** Namespace collecting all the Wallet-related classes. */
  36. namespace KWallet {
  37.  
  38. /**
  39.  * KDE Wallet
  40.  *
  41.  * This class implements a generic system-wide Wallet for KDE.  This is the
  42.  * ONLY public interface.  The DCOP client is unsupported and considered to be
  43.  * private.
  44.  *
  45.  * @author George Staikos <staikos@kde.org>
  46.  * @short KDE Wallet Class
  47.  */
  48. class KIO_EXPORT Wallet : public QObject, public DCOPObject {
  49.     K_DCOP
  50.     Q_OBJECT
  51.     protected:
  52.         /**
  53.          *  Construct a KWallet object.
  54.          *  @internal
  55.          *  @param handle The handle for the wallet.
  56.          *  @param name The name of the wallet.
  57.          */
  58.         Wallet(int handle, const QString& name);
  59.         /**
  60.          *  Copy a KWallet object.
  61.          *  @internal
  62.          */
  63.         Wallet(const Wallet&);
  64.  
  65.     public:
  66.         enum EntryType { Unknown=0, Password, Stream, Map, Unused=0xffff };
  67.  
  68.         /**
  69.          *  Destroy a KWallet object.  Closes the wallet.
  70.          */
  71.         virtual ~Wallet();
  72.         
  73.         /**
  74.          *  List all the wallets available.
  75.          *  @return Returns a list of the names of all wallets that are
  76.          *          open.
  77.          */
  78.         static QStringList walletList();
  79.  
  80.         /**
  81.          *  Determine if the KDE wallet is enabled.  Normally you do
  82.          *  not need to use this because open() will just fail.
  83.          *  @return Returns true if the wallet enabled, else false.
  84.          */
  85.         static bool isEnabled();
  86.  
  87.         /**
  88.          *  Determine if the wallet @p name is open by any application.
  89.          *  @param name The name of the wallet to check.
  90.          *  @return Returns true if the wallet is open, else false.
  91.          */
  92.         static bool isOpen(const QString& name);
  93.  
  94.         /**
  95.          *  Close the wallet @p name.  The wallet will only be closed
  96.          *  if it is open but not in use (rare), or if it is forced
  97.          *  closed.
  98.          *  @param name The name of the wallet to close.
  99.          *  @param force Set true to force the wallet closed even if it
  100.          *               is in use by others.
  101.          *  @return Returns 0 on success, non-zero on error.
  102.          */
  103.         static int closeWallet(const QString& name, bool force);
  104.  
  105.         /**
  106.          *  Delete the wallet @p name.  The wallet will be forced closed
  107.          *  first.
  108.          *  @param name The name of the wallet to delete.
  109.          *  @return Returns 0 on success, non-zero on error.
  110.          */
  111.         static int deleteWallet(const QString& name);
  112.  
  113.         /**
  114.          *  Disconnect the application @p app from @p wallet.
  115.          *  @param wallet The name of the wallet to disconnect.
  116.          *  @param app The name of the application to disconnect.
  117.          *  @return Returns true on success, false on error.
  118.          */
  119.         static bool disconnectApplication(const QString& wallet, const QCString& app);
  120.  
  121.         enum OpenType { Synchronous=0, Asynchronous, Path, OpenTypeUnused=0xff };
  122.  
  123.         /**
  124.          *  Open the wallet @p name.  The user will be prompted to
  125.          *  allow your application to open the wallet, and may be
  126.          *  prompted for a password.  You are responsible for deleting
  127.          *  this object when you are done with it.
  128.          *  @param name The name of the wallet to open.
  129.          *  @param ot    If Asynchronous, the call will return
  130.          *               immediately with a non-null pointer to an
  131.          *               invalid wallet.  You must immediately connect
  132.          *               the walletOpened() signal to a slot so that
  133.          *               you will know when it is opened, or when it
  134.          *               fails.
  135.          *  @param w The window id to associate any dialogs with.
  136.          *  @return Returns a pointer to the wallet if successful,
  137.          *          or a null pointer on error or if rejected.
  138.          */
  139.         static Wallet* openWallet(const QString& name, WId w = 0, OpenType ot = Synchronous);
  140.  
  141.         /**
  142.          *  List the applications that are using the wallet @p wallet.
  143.          *  @param wallet The wallet to query.
  144.          *  @return Returns a list of all DCOP application IDs using
  145.          *          the wallet.
  146.          */
  147.         static QStringList users(const QString& wallet);
  148.  
  149.         /**
  150.          *  The name of the wallet used to store local passwords.
  151.          */
  152.         static const QString LocalWallet();
  153.  
  154.         /**
  155.          *  The name of the wallet used to store network passwords.
  156.          */
  157.         static const QString NetworkWallet();
  158.  
  159.         /**
  160.          *  The standardized name of the password folder.
  161.          *  It is automatically created when a wallet is created, but
  162.          *  the user may still delete it so you should check for its
  163.          *  existence and recreate it if necessary and desired.
  164.          */
  165.         static const QString PasswordFolder();
  166.  
  167.         /**
  168.          *  The standardized name of the form data folder.
  169.          *  It is automatically created when a wallet is created, but
  170.          *  the user may still delete it so you should check for its
  171.          *  existence and recreate it if necessary and desired.
  172.          */
  173.         static const QString FormDataFolder();
  174.  
  175.         /**
  176.          *  Request to the wallet service to change the password of
  177.          *  the wallet @p name.
  178.          *  @param name The the wallet to change the password of.
  179.          *  @param w The window id to associate any dialogs with.
  180.          */
  181.         static void changePassword(const QString& name, WId w = 0);
  182.  
  183.         /**
  184.          *  This syncs the wallet file on disk with what is in memory.
  185.          *  You don't normally need to use this.  It happens
  186.          *  automatically on close.
  187.          *  @return Returns 0 on success, non-zero on error.
  188.          */
  189.         virtual int sync();
  190.  
  191.         /**
  192.          *  This closes and locks the current wallet.  It will
  193.          *  disconnect all applications using the wallet.
  194.          *  @return Returns 0 on success, non-zero on error.
  195.          */
  196.         virtual int lockWallet();
  197.  
  198.         /**
  199.          *  The name of the current wallet.
  200.          */
  201.         virtual const QString& walletName() const;
  202.  
  203.         /**
  204.          *  Determine if the current wallet is open, and is a valid
  205.          *  wallet handle.
  206.          *  @return Returns true if the wallet handle is valid and open.
  207.          */
  208.         virtual bool isOpen() const;
  209.  
  210.         /**
  211.          *  Request to the wallet service to change the password of
  212.          *  the current wallet.
  213.          *  @param w The window id to associate any dialogs with.
  214.          */
  215.         virtual void requestChangePassword(WId w = 0);
  216.  
  217.         /**
  218.          *  Obtain the list of all folders contained in the wallet.
  219.          *  @return Returns an empty list if the wallet is not open.
  220.          */
  221.         virtual QStringList folderList();
  222.  
  223.         /**
  224.          *  Determine if the folder @p f exists in the wallet.
  225.          *  @param f the name of the folder to check for
  226.          *  @return Returns true if the folder exists in the wallet.
  227.          */
  228.         virtual bool hasFolder(const QString& f);
  229.  
  230.         /**
  231.          *  Set the current working folder to @p f.  The folder must
  232.          *  exist, or this call will fail.  Create a folder with
  233.          *  createFolder().
  234.          *  @param f the name of the folder to make the working folder
  235.          *  @return Returns true if the folder was successfully set.
  236.          */
  237.         virtual bool setFolder(const QString& f);
  238.  
  239.         /**
  240.          *  Remove the folder @p f and all its entries from the wallet.
  241.          *  @param f the name of the folder to remove
  242.          *  @return Returns true if the folder was successfully removed.
  243.          */
  244.         virtual bool removeFolder(const QString& f);
  245.  
  246.         /**
  247.          *  Created the folder @p f.
  248.          *  @param f the name of the folder to create
  249.          *  @return Returns true if the folder was successfully created.
  250.          */
  251.         virtual bool createFolder(const QString& f);
  252.  
  253.         /**
  254.          *  Determine the current working folder in the wallet.
  255.          *  If the folder name is empty, it is working in the global
  256.          *  folder, which is valid but discouraged.
  257.          *  @return Returns the current working folder.
  258.          */
  259.         virtual const QString& currentFolder() const;
  260.  
  261.         /**
  262.          *  Return the list of keys of all entries in this folder.
  263.          *  @return Returns an empty list if the wallet is not open, or
  264.          *          if the folder is empty.
  265.          */
  266.         virtual QStringList entryList();
  267.  
  268.         /**
  269.          *  Rename the entry @p oldName to @p newName.
  270.          *  @param oldName The original key of the entry.
  271.          *  @param newName The new key of the entry.
  272.          *  @return Returns 0 on success, non-zero on error.
  273.          */
  274.         virtual int renameEntry(const QString& oldName, const QString& newName);
  275.  
  276.         /**
  277.          *  Read the entry @p key from the current folder.
  278.          *  The entry format is unknown except that it is either a
  279.          *  QByteArray or a QDataStream, which effectively means that
  280.          *  it is anything.
  281.          *  @param key The key of the entry to read.
  282.          *  @param value A buffer to fill with the value.
  283.          *  @return Returns 0 on success, non-zero on error.
  284.          */
  285.         virtual int readEntry(const QString& key, QByteArray& value);
  286.  
  287.         /**
  288.          *  Read the map entry @p key from the current folder.
  289.          *  @param key The key of the entry to read.
  290.          *  @param value A map buffer to fill with the value.
  291.          *  @return Returns 0 on success, non-zero on error.  Will
  292.          *          return an error if the key was not originally
  293.          *          written as a map.
  294.          */
  295.         virtual int readMap(const QString& key, QMap<QString,QString>& value);
  296.  
  297.         /**
  298.          *  Read the password entry @p key from the current folder.
  299.          *  @param key The key of the entry to read.
  300.          *  @param value A password buffer to fill with the value.
  301.          *  @return Returns 0 on success, non-zero on error.  Will
  302.          *          return an error if the key was not originally
  303.          *          written as a password.
  304.          */
  305.         virtual int readPassword(const QString& key, QString& value);
  306.  
  307.         /**
  308.          *  Read the entries matching @p key from the current folder.
  309.          *  The entry format is unknown except that it is either a
  310.          *  QByteArray or a QDataStream, which effectively means that
  311.          *  it is anything.
  312.          *  @param key The key of the entry to read.  Wildcards
  313.          *             are supported.
  314.          *  @param value A buffer to fill with the value.  The key in
  315.          *               the map is the entry key.
  316.          *  @return Returns 0 on success, non-zero on error.
  317.          *  @since 3.4
  318.          */
  319.         int readEntryList(const QString& key, QMap<QString, QByteArray>& value);
  320.  
  321.         /**
  322.          *  Read the map entry @p key from the current folder.
  323.          *  @param key The key of the entry to read.  Wildcards
  324.          *             are supported.
  325.          *  @param value A buffer to fill with the value.  The key in
  326.          *               the map is the entry key.
  327.          *  @return Returns 0 on success, non-zero on error.  Will
  328.          *          return an error if the key was not originally
  329.          *          written as a map.
  330.          *  @since 3.4
  331.          */
  332.         int readMapList(const QString& key, QMap<QString, QMap<QString, QString> >& value);
  333.  
  334.         /**
  335.          *  Read the password entry @p key from the current folder.
  336.          *  @param key The key of the entry to read.  Wildcards
  337.          *             are supported.
  338.          *  @param value A buffer to fill with the value.  The key in
  339.          *               the map is the entry key.
  340.          *  @return Returns 0 on success, non-zero on error.  Will
  341.          *          return an error if the key was not originally
  342.          *          written as a password.
  343.          *  @since 3.4
  344.          */
  345.         int readPasswordList(const QString& key, QMap<QString, QString>& value);
  346.  
  347.         /**
  348.          *  Write @p key = @p value as a binary entry to the current
  349.          *  folder.  Be careful with this, it could cause inconsistency
  350.          *  in the future since you can put an arbitrary entry type in
  351.          *  place.
  352.          *  @param key The key of the new entry.
  353.          *  @param value The value of the entry.
  354.          *  @param entryType The type of the entry.
  355.          *  @return Returns 0 on success, non-zero on error.
  356.          */
  357.         virtual int writeEntry(const QString& key, const QByteArray& value, EntryType entryType);
  358.  
  359.         /**
  360.          *  Write @p key = @p value as a binary entry to the current
  361.          *  folder.
  362.          *  @param key The key of the new entry.
  363.          *  @param value The value of the entry.
  364.          *  @return Returns 0 on success, non-zero on error.
  365.          */
  366.         virtual int writeEntry(const QString& key, const QByteArray& value);
  367.  
  368.         /**
  369.          *  Write @p key = @p value as a map to the current folder.
  370.          *  @param key The key of the new entry.
  371.          *  @param value The value of the map.
  372.          *  @return Returns 0 on success, non-zero on error.
  373.          */
  374.         virtual int writeMap(const QString& key, const QMap<QString,QString>& value);
  375.  
  376.         /**
  377.          *  Write @p key = @p value as a password to the current folder.
  378.          *  @param key The key of the new entry.
  379.          *  @param value The value of the password.
  380.          *  @return Returns 0 on success, non-zero on error.
  381.          */
  382.         virtual int writePassword(const QString& key, const QString& value);
  383.  
  384.         /**
  385.          *  Determine if the current folder has they entry @p key.
  386.          *  @param key The key to search for.
  387.          *  @return Returns true if the folder contains @p key.
  388.          */
  389.         virtual bool hasEntry(const QString& key);
  390.  
  391.         /**
  392.          *  Remove the entry @p key from the current folder.
  393.          *  @param key The key to remove.
  394.          *  @return Returns 0 on success, non-zero on error.
  395.          */
  396.         virtual int removeEntry(const QString& key);
  397.  
  398.         /**
  399.          *  Determine the type of the entry @p key in this folder.
  400.          *  @param key The key to look up.
  401.          *  @return Returns an enumerated type representing the type
  402.          *          of the entry.
  403.          */
  404.         virtual EntryType entryType(const QString& key);
  405.  
  406.         /**
  407.          *  Determine if a folder does not exist in a wallet.  This
  408.          *  does not require decryption of the wallet.
  409.          *  This is a handy optimization to avoid prompting the user
  410.          *  if your data is certainly not in the wallet.
  411.          *  @param wallet The wallet to look in.
  412.          *  @param folder The folder to look up.
  413.          *  @return Returns true if the folder does NOT exist in the
  414.          *  wallet, or the wallet does not exist.
  415.          */
  416.         static bool folderDoesNotExist(const QString& wallet, const QString& folder);
  417.  
  418.         /**
  419.          *  Determine if an entry in a folder does not exist in a
  420.          *  wallet.  This does not require decryption of the wallet.
  421.          *  This is a handy optimization to avoid prompting the user
  422.          *  if your data is certainly not in the wallet.
  423.          *  @param wallet The wallet to look in.
  424.          *  @param folder The folder to look in.
  425.          *  @param key The key to look up.
  426.          *  @return Returns true if the key does NOT exist in the
  427.          *  wallet, or the folder or wallet does not exist.
  428.          */
  429.         static bool keyDoesNotExist(const QString& wallet, const QString& folder, 
  430.                         const QString& key);
  431.  
  432.     signals:
  433.         /**
  434.          *  Emitted when this wallet is closed.
  435.          */
  436.         void walletClosed();
  437.  
  438.         /**
  439.          *  Emitted when a folder in this wallet is updated.
  440.          *  @param folder The folder that was updated.
  441.          */
  442.         void folderUpdated(const QString& folder);
  443.  
  444.         /**
  445.          *  Emitted when the folder list is changed in this wallet.
  446.          */
  447.         void folderListUpdated();
  448.  
  449.         /**
  450.          *  Emitted when a folder in this wallet is removed.
  451.          *  @param folder The folder that was removed.
  452.          */
  453.         void folderRemoved(const QString& folder);
  454.  
  455.         /**
  456.          *  Emitted when a wallet is opened in asynchronous mode.
  457.          *  @param success True if the wallet was opened successfully.
  458.          */
  459.         void walletOpened(bool success);
  460.  
  461.     private:
  462.     k_dcop:
  463.         /**
  464.          *  @internal
  465.          *  DCOP slot for signals emitted by the wallet service.
  466.          */
  467.         ASYNC slotWalletClosed(int handle);
  468.  
  469.         /**
  470.          *  @internal
  471.          *  DCOP slot for signals emitted by the wallet service.
  472.          */
  473.         ASYNC slotFolderUpdated(const QString& wallet, const QString& folder);
  474.  
  475.         /**
  476.          *  @internal
  477.          *  DCOP slot for signals emitted by the wallet service.
  478.          */
  479.         ASYNC slotFolderListUpdated(const QString& wallet);
  480.  
  481.         /**
  482.          *  @internal
  483.          *  DCOP slot for signals emitted by the wallet service.
  484.          */
  485.         ASYNC slotApplicationDisconnected(const QString& wallet, const QCString& application);
  486.  
  487.         /**
  488.          *  @internal
  489.          *  Callback for kwalletd
  490.          */
  491.         ASYNC walletOpenResult(int rc);
  492.  
  493.     private slots:
  494.         /**
  495.          *  @internal
  496.          *  Used to detect when the wallet service dies.
  497.          */
  498.         void slotAppUnregistered(const QCString&);
  499.  
  500.     private:
  501.         class WalletPrivate;
  502.         WalletPrivate *d;
  503.         QString _name;
  504.         QString _folder;
  505.         int _handle;
  506.         DCOPRef *_dcopRef;
  507.  
  508.     protected:
  509.         /**
  510.          *  @internal
  511.          */
  512.         virtual void virtual_hook(int id, void *data);
  513. };
  514.  
  515. }
  516.  
  517. #endif //Q_OS_UNIX
  518.  
  519. #endif //_KWALLET_H
  520.  
  521.